
                        CPU Load Average Monitor
                        ========================


Documentation for !CPUload desktop utility version 3.30 11-Apr-2020

Issue: 3.30 11-Apr-2020, replaces:      0.10 24-Mar-1991
                                        1.00 25-Mar-1991
                                        2.00 08-Jun-1991
                                        2.50 28-Feb-1994
                                        3.10 07-Mar-1998
                                        3.20 08-Jan-2000
                                        3.22 18-Aug-2001
                                        3.23 23-Jun-2013

Author: David J Ruck

Copyright  DEEJ Technology PLC 1991-2013



Overview
========


!CPUload is designed to graphically show the amount of work the CPU (ARM
chip) is doing, in the style of the X windows utility xload. It provides an
alternative to Acorn's !Usage, supplied on the original RISC OS Applications
Discs, with several major enhancements, including:

        (1)       More accurate calculation & display of CPU load.

        (2)       Fully re-sizeable in both height (load axis) 
                  and width (time axis).

        (3)       User selectable update rate, 100ms to 5 seconds.

        (4)       400 load average point store.

        (5)       Full automatic and manual scaling options.

        (6)       Uses a very low amount of CPU time in operation.

The CPU load average is calculated from the number of calls and amount of
time between the Window manager Wimp_Poll Idle events being delivered to
!CPUload, this is used to determine the responsiveness of the machine.

The calculated CPU load average is displayed as black vertical bars in the
!CPUload window. After every update period the window scrolls to the left
and another bar is plotted.

The display automatically scaled to accommodate the largest value currently
in the window. The update rate and manual scaling can be selected via a
menu.



Using !CPUload
==============

On starting !CPUload a window is displayed immediately, it does not install
an icon on the icon bar. The !CPUload window is slightly different from most
RISC OS windows, in that it does not have horizontal or vertical scroll
bars, but it does have toggle and resize icons on the right of the title bar
- these can be used to resize the window in the standard RISC OS manner.

!CPUload holds a large number of load average points, so increasing the
horizontal size of the window will reveal previous values which have
disappeared off the left of the window (if the program has been running long
enough). Increasing the vertical size will enable more detail to be shown,
by using a larger scale.

  
!CPUload menu
-------------
The !CPUload menu options and sub menus are described below.

Info                    Displays program information and version number.



Update                  The update sub menu is used to select an update rate
                        in centi-seconds (1/100 second). The default is 50cs
                        or 2 updates per second. Low values can be used to
                        monitor small bursts of activity, 500cs enables over
                        an hours worth of CPU load to be monitored with the
                        maximum window width.

                        Note: the size of the bars produced at the same load
                        average is not the same for different update rates.

Scale                   The scale of the window is shown by light grey
                        horizontal lines, these do not represent values, but
                        the number of times the height of the vertical bars
                        has been halved. Thus no lines is the default scale,
                        1 line  =  scale, 
                        2 lines =  scale and 
                        8 lines = 1/256th scale, etc.

                        The automatic scaling (Auto ticked) ensures that the
                        largest bar currently in the window will fit. The
                        scale will change if a new large bar enters the
                        window or the largest bar falls off the left of the
                        window. Adjusting the horizontal size of the window
                        will affect the scale depending on the values moved
                        in or out of the window. Adjusting the vertical size
                        can also affect the scale.

                        The problem with automatic scaling is that if a very
                        large load blip occurs, other bars will become much
                        smaller, losing detail. Selecting and entering a
                        value in the Max scale sub-menu will limit the scale
                        used, smaller scales will still be used if possible.

                        Selecting and entering a value in Fixed scale will
                        only allow this scale to be used. Both the Max scale
                        and Fixed scale values correspond to the number of
                        light grey scale lines displayed.

Quit                    Removes !CPUload, having the same effect as click on
                        the window close icon.



Programming advice
==================

One problem which RISC OS application programmer's face is deciding on the
amount of time that should be spent in idle processing - that is routines
that run in the background using the idle events returned by Wimp_Poll.
Choosing too low a time will make the program inefficient, but too high a
time is anti-social to other active applications, making the machine feel
sluggish.

Unfortunately the RISC OS Programmers Reference Manuals only state this
fact, and do not provide firm timing values. Using !CPUload, a reference can
be obtained against a standard test, such as running the C compiler in an
DDE task window. You can then tailor your program to produce a mean load
equivalent to this under the same conditions.


History
=======

3.20 08-Jan-2000  Fixed window stopping when displayed task dies
                  Window titles given an instance number of WindOpen use
3.21 06-Feb-2000  Titlebar toggle gets window stacking order right
                  Titlebar doesn't invert when clicked on RISC OS 4
3.22 18-Aug-2001  Official AppStat SWI chunk used                  

3.23 23-Jun-2013  Updated version of APPstat module, correcting abort on
                  Raspberry Pi and improving accuracy on other systems when 
                  counter period has been reduced by the NetTime module
                  
3.30 11-Apr-2020  APPstat module fix for HAL calls corrupting registers on
                  Mini.m
 
End of !CPUload.!Help

